Inside Macintosh: Open Transport /

Chapter 10 - AppleTalk Addressing

Using AppleTalk Addressing

This section explains how you use AppleTalk addressing formats to identify an endpoint and how you use various Open Transport AppleTalk functions to

• initialize an address
• compare two DDP addresses
• register the name of your endpoint
• look up names and addresses to find a specific applicaiton or user name
• manipulate NBP names by using NBP entity structures
• initialize NBP entities
• set and extract the name, type, or zone parts of an NBP name

Specifying a DDP Address

The primary address format is the DDP address format, which is the most commonly used. It identifies the physical socket address for your endpoint. Data transmission is fastest for those functions that use this address format because no lookup or conversion is necessary for Open Transport to find the specified physical location. Functions that use the NBP address format, for example, have to look up the mapping of the NBP name to its physical address, and this extra step slows down communications.

Functions such as OTBind, OTGetProtAddress, and OTResolveAddress return an address in this format. DDP addresses use the DDP address structure (defined by the DDPAddress data type), which includes the following fields:

Field	Meaning
Address type	The type of address format
Network number	The endpoint's network
Node ID	The endpoint's node
Socket number	The endpoint's socket
DDP type	A DDP endpoint's type of protocol

Permissable values for these fields are given in the section "The DDP Address Structure" on page 10-16. The DDP type field is discussed further in the chapter "Datagram Delivery Protocol" in this book.

When you bind an AppleTalk endpoint, you typically specify a network number of 0 and a node ID of 0, or leave both fields blank. In most cases, the combination of the network number, the node ID, and the socket number creates a unique identifier for any socket in the AppleTalk internet so that AppleTalk's delivery protocol, DDP, can deliver packets to the correct destination.

Since the DDP type field is ignored by all protocols other than DDP, set this field to 0 unless you plan to use the DDP protocol. For more information on DDP types, see the chapter "Datagram Delivery Protocol (DDP)" in this book.

In using Open Transport functions to send or receive data, you use a TNetbuf structure to point to a buffer that holds data for a specific Open Transport function. Listing 10-1 shows how you set up the fields of a DDP address and how you set up a TNetbuf structure for it.

Listing 10-1 Setting up a DDP Address

void DoCreateDDPAddress(TNetbuf *theNetBuf, long net, short node, 
                   short socket)
{
   DDPAddress *ddpAddress;

   /* Allocate memory for the DDPAddress structure. */
   ddpAddress = (DDPAddress*) NewPtr(sizeof(DDPAddress));

   /* Set up a DDPAddress structure. */
   ddpAddress->fAddressType   = AF_ATALK_DDP;
   ddpAddress->fNetwork       = net;
   ddpAddress->fNode          = node;
   ddpAddress->fSocket        = socket;
   ddpAddress->fDDPType       = 0;
   ddpAddress->fPad           = 0;

   /* Set the TNetbuf to point to it. */
   theNetbuf->len       = sizeof(DDPAddress);
   theNetbuf->maxlen    = sizeof(DDPAddress);
   theNetbuf->buf       = (void*)ddpAddress;
} 

Specifying an NBP Address

You can use the NBP address format to identify an endpoint when you know the user-defined name of an endpoint but not its physical address. Applications that run on an Open Transport AppleTalk network can display these user-
friendly NBP names to users while using the DDP addresses internally to locate and address entities. See the section "Looking Up Names and Addresses," beginning on page 10-11 for more information on how Open Transport translates an NBP name into a physical address.

The NBP address format is defined by the NBP address structure, which includes the following fields:

Field	Meaning
Address type	The type of address format
NBP name buffer	A pointer to a text string giving the endpoint's NBP name

The values for these fields are discussed more fully in the section "The NBP Address Structure" on page 10-17. Note that NBP addresses do not "know" the length of the NBP name you might use. To find out its length, you must use the OTResolveAddress or OTLookupName functions.

An NBP name consists of these three fields: name, type, and zone. The value for each of these fields is an alphanumeric string of up to 32 characters. The NBP name is not case sensitive. When you bind an endpoint with an NBP address, you must specify a value for the name and type fields, but you don't have to specify the zone. The NBP name string is not null-terminated and is in the form

name:type@zone

The name field typically identifies the user of the system or, in the case of a server, the system itself. For example, you could use the name field to register a serial number for your application and then use a mapper provider to search to see if this matches any other NBP name. If it does, your application could branch to some specialized code to prevent the duplicate application from launching or to issue a warning message as part of a software protection scheme.

The type field generally identifies the type of service that the entity provides, for example, "Mailbox" for an electronic mailbox on a server. Applications offering similar services can find one another and identify potential partners by looking up only those addresses with a specific type. You could request the mapper provider to return the names of all of the registered entities of a certain type, for example, all compiler servers and laser printers.

The zone field identifies the zone within the network to which the node belongs. To indicate the current zone (or no zone, as in the case of a simple network configuration not divided into zones), you can leave this field blank (the preferred method) or you can specify an asterisk (*). To Open Transport, these two methods are equivalent; thus, the strings "MyName:MBOX@*" and "MyName:MBOX" identify the same zone. There are several functions for getting zone information; these are described in the chapter "AppleTalk Service Providers" in this book.

When you use an NBP structure to define an NBP address format, you copy the string specifying the NBP name into the NBP name buffer.

You can use the backslash (\) character in an NBP name to include the colon (:), at sign (@), and the backslash (\) characters in the name. For example, if you wanted to use the name "My\Machine," the type "My:Server" and the zone "My@Zone," you would express it in the following way:

My\\Machine:My\:Server@My\@Zone

The maximum size of the NBP name buffer is currently defined to be 105 bytes. This permits a string whose name, type, and zone fields each contain the maximum 32 characters, plus 2 bytes for the separator characters (: and @) and 7 bytes for escape characters--that is, combinations of backslash-colon (\:), backslash-at sign (\@), or backslash-backslash (\\).

If you specify an NBP address structure when binding an endpoint, Open Transport assigns a dynamic socket number to the DDP address of the endpoint (because the NBP address cannot supply any socket number) and registers the NBP name you specified for your application.

Listing 10-2 shows how you set up the fields of an NBP address. The statements used to set the size of the len and maxlen fields of the TNetbuf structure simply add the size of the two fields of the NBP address structure: the size of the constant name plus the length of the string equals the length of data stored in the buffer.

Listing 10-2 Setting up an NBP address

void DoCreateNBPAddress(TNetbuf *theNetBuf, char* nbpName)
{
   NBPAddress *nbpAddress;
   short nbpSize;

   /* Allocate memory for an NBP structure. */
   nbpSize = sizeof(OTAddressType) + strlen(nbpName);
   nbpAddress = (NBPAddress*) NewPtr(nbpSize);

   /* Set up an NBPAddress structure. */
   nbpAddress->fAddressType   = AF_ATALK_NBP;
   strcpy(nbpAddress->fNBPNameBuffer, nbpName);

   /* Set the TNetbuf to point to it. */
   theNetbuf->len       = nbpSize;
   theNetbuf->maxlen    = nbpSize;
   theNetbuf->buf       = (void*)nbpAddress;
} 

Specifying a Combined DDP-NBP Address

You use the the combined DDP-NBP address format when you want to bind an endpoint with a specific NBP name to a specific socket. As the name suggests, this format combines the DDP address and the NBP address. Its data structure begins, as do all of the address structures, with a constant defining which address format to use; then it includes all the standard DDP address fields and ends with the standard NBP name buffer field. See the previous two subsections, "Specifying a DDP Address" and "Specifying an NBP Address," and the section "The Combined DDP-NBP Address Structure" on page 10-17 for discussion of these fields, and also refer to Inside AppleTalk, second edition.

Specifying and Using a Multinode Address

You use the multinode address format for multinode applications that want to bind several multinode endpoints to the same socket using different node IDs for each. The multinode address format is identical to the DDP address format except that you use a different constant to identify it. See the section "Specifying a DDP Address" on page 10-5 and the section "The Multinode Address Structure" on page 10-19 for discussion of these fields.

The significant fields for the multinode address format are the network number and node ID. DDP ignores the other fields. You can request specific values for the network number and node ID when binding an endpoint although, as usual, the address returned by the OTBind function contains the actual network and node values that the endpoint has been bound to.

DDP delivers any packet addressed to the bound multinode address whether or not a specific socket or DDP type is specified for the destination address of the packet. Applications that have opened multinode endpoints must perform their own filtering if the socket or DDP type values are important.

Registering Your Endpoint's Name

In order for you to make the name of your AppleTalk endpoint visible to other applications on a network, you have to register its name. There are two ways to do this. The easiest way is for you to simply use the OTBind function to bind your endpoint with the NBP address format or the combined DDP-NBP address format. If you use the NBP address format, during the binding process Open Tranport registers your endpoint's name and dynamically assigns a physical socket to your endpoint. If you use the combined DDP-NBP address format, you can specify the physical socket you want to bind the endpoint to. The OTBind function is discussed in the chapter "Endpoints" in this book.

The other way to register an endpoint's name involves several additional steps: You have to first bind your endpoint, open an NBP mapper provider, use the Open Transport name-registration function, OTRegisterName, as a separate step, and then close the NBP mapper provider. You must use this more complex method if you want to register more than one endpoint on the same socket.

In either case, Open Transport uses NBP to associate the endpoint's name with its physical address. Once your endpoint is registered, it is a network-visible entity that other applications can locate.

When you register a name with the OTRegisterName function, the function returns a unique identifier for the registered name. If you later want to delete the name, you can use this identifier to delete it with the OTDeleteNameByID function. This method is more convenient than the alternative OTDeleteName function. The OTRegisterName, OTDeleteName, and OTDeleteNameByID functions are discussed in the chapter "Endpoints" in this book. Table 10-1 provides a summary of the Open Transport name-registration functions.

Table 10-1 Open Transport name-registration functions

Function	Provider	Use
OTBind	Endpoint	Registers the specified NBP name when you bind with the NBP address or the combined DDP-NBP address formats
OTRegisterName	Mapper	Registers the specified name
OTDeleteName	Mapper	Removes a name that was previously registered dynamically
OTDeleteNameByID	Mapper	Removes a name that was previously registered dynamically

Looking Up Names and Addresses

To communicate with an endpoint, Open Transport needs its physical address. There are endpoint and mapper functions you can use to obtain this address, two of which allow you to specify the endpoint's NBP name. In these instances, Open Transport performs a name lookup that resolves the NBP name into a physical name that it can use to locate the endpoint you want. Table 10-2 provides a summary of the Open Transport functions that create or return endpoint name and address information.

Table 10-2 Open Transport name and address functions

Function	Provider	Use
OTGetProtAddress	Endpoint	Obtains your endpoint's DDP address. For connection-oriented endpoints that are connected to another endpoint, it also obtains the remote endpoint's address.
OTResolveAddress	Endpoint	Obtains the DDP address that corresponds to the specified NBP name.
OTLookUpName	Mapper	Obtains the address for the specified name or a list of addresses for the specified name pattern. You can also use this function to verify that a specified name is still available on the network and that it is associated with a specified address.
OTATalkGetInfo	AppleTalk service	Obtains addressing information about the current environment of an AppleTalk node.

You can improve performance in certain circumstances if you use the endpoint OTResolveAddress function instead of the mapper OTLookUpName function. Calling OTResolveAddress resolves the name into a physical address by using information that is maintained in the current node whereas the OTLookUpName function has to go out over the network to look up its information. For example, if you are going to use an NBP address structure repeatedly to specify a remote endpoint in a connectionless or transaction-based service, you can speed up your processing if you first use the OTResolveAddress function to resolve the NBP address into a DDP address and then subsequently use only that DDP address to specify the remote endpoint. Otherwise, an NBP lookup could occur on the network for every packet and slow down communications.

When you call the OTLookUpName function to obtain the address associated with an NBP name, you can specify a name pattern rather than a complete name by using wildcard operators for the variable parts of the name. Table 10-3 shows the wildcard operators that you can use to specify a name pattern for a name specified as a partial name.

Table 10-3 Wildcard operators

Character	Meaning
=	All possible values. You can use the equal sign (=) alone in the name or type field.
í	Any or no characters in this position. You can use the double tilde (í) to obtain matches for name or type fields. For example, "paíl" matches "pal," "paul," and "paper ball." You can use only one double tilde in any string. If you use the double tilde alone, it has the same meaning as the equal sign (=). Press Option-X to type the double tilde character (í) on a Macintosh keyboard.
*	Your local zone. You can leave this blank (preferred method) or use the asterisk (*) to indicate the zone to which this node belongs.

Depending on how you structure the name pattern with wildcards, the OTLookUpName function can return a list of names if more than one name matches the specified pattern. For example, if you want to retrieve the names and addresses of all the applications defined with a given type, such as mailboxes, in the same zone as the one in which your process is running, you can set the name field to the equal sign (=), set the type field to "Mailbox," and leave the zone field blank. The OTLookUpName function returns the NBP names and DDP addresses of all mailboxes in that zone.

Manipulating an NBP Name

If you need to store or manipulate the name, type, or zone part of an NBP name separately, you need to use an NBP entity structure, which is a data structure that Open Transport provides for this purpose. Open Transport also provides several utility functions to transfer data between NBP entities and NBP names.

The NBP entity structure holds an NBP name in the form name:type@zone, with each part containing the maximum 32 characters plus a length byte, for a total possible length of 99 bytes. The NBP entity itself does not contain escape characters, but the NBP entity extraction functions insert a backslash (\) in front of any backslash, colon (:), or at sign (@) they find in an NBP name so that mapper functions can use a correctly formatted NBP name.

You can initialize an NBP entity and then load it with the name, type, and zone of an NBP name individually (the OTSetNBPName, OTSetNBPType, and OTSetNBPZone functions), or you can load an NBP entity with an entire NBP address at one time (the OTSetNBPEntityFromAddress function). Once you have loaded an NBP entity, you can find out how much buffer space it actually uses for the NBP name it holds (the OTGetNBPEntityLengthAsAddress function). You can then extract each individual NBP name part one at a time (the OTExtractNBPName, OTExtractNBPType, and OTExtractNBPZone functions), or you can copy the entire NBP entity into an NBP address structure (the OTSetAddressFromNBPEntity function).